Context Navigation

Subtitles API

Introduction to OSDb

XMLRPC API Methods

Introduction to OSDb
ServerInfo
LogIn
LogOut
SearchSubtitles
SearchToMail
CheckSubHash
CheckMovieHash
CheckMovieHash2
InsertMovieHash
TryUploadSubtitles
UploadSubtitles
DetectLanguage
PreviewSubtitles
DownloadSubtitles
ReportWrongMovieHash
ReportWrongImdbMovie
GetSubLanguages
GetAvailableTranslations
GetTranslation
SearchMoviesOnIMDB
GetIMDBMovieDetails
InsertMovie
SubtitlesVote
GetComments
AddComment
AddRequest
SetSubscribeUrl
SubscribeToHash
QuickSuggest
SuggestMovie
GetUserInfo
GuessMovieFromString
AutoUpdate
NoOperation

Subtitles API
Instructions
Common errors
XMLRPC methods
Status codes
UserRank lists
Supported tags

We decided use XMLRPC (see spec and implementations) as default API for opensubtitles.org. Our API supports many methods, so there should not be a problem code some nice applications.

Wikipedia: XML-RPC is a very simple protocol, defining only a handful of data types and commands, and the entire description can be printed on two pages of paper. This is in stark contrast to most RPC systems, where the standards documents often run into the hundreds of pages and require considerable software support in order to be used.

Instructions

REST JSON search Introduced public JSON search using REST.
Read this first - Before developing let us know, we assign useragent to you, empty useragent or unregistered UA will not work.
before using this XML-RPC is required to have implementation for OS HASH
we recommend to use HTTPS - you can use https://api.opensubtitles.org:443/xml-rpc
XML-RPC requests send to https://api.opensubtitles.org/xml-rpc, you may be interested in more verbose version of XML-RPC methods with examples
API Request limit: 40 HTTP requests per 10 seconds per IP address, read here more https://forum.opensubtitles.org/viewtopic.php?f=8&t=16072
Check HTTP Response header 'X-RateLimit-Remaining' for http requests remaining per given period.
For languages codes, check ISO639, use pb/pob for Portuguese (Brazil) - Download OS languages table dump
IMDB ID is meant to be NUMBER from link of IMDB movie. Example: http://www.imdb.com/title/tt0133093/ - IMDB ID is '0133093' (removing leading 0 is also OK).
PHP: for gzip compression use function which adds no header to output, gzcompress - this means, in your programming language you might look for zlib instead of gzip. For decompression is used gzdecompress.
PHP: if you download subtitles from XML-RPC, use: gzinflate(substr(base64_decode($subs_b64_data_from_xmlrpc),10)), if gz from web: gzinflate(substr($gz_subtitles),10);
Handle properly HTTP status codes, sometimes you might get 5xx
if you get 407 Download limit reached, do not use persistent connections (HTTP keep-alive) and don't download more than 200 subtitles per 24 hour per IP/User. If user wants more, he can Become OpenSubtitles VIP member - thats one of the many reasons, why your app should allow user to login.
if you want search uploads by useragent, use this link: http://www.opensubtitles.org/search/sublanguageid-all/useragent-$UserAgent
for testing XML-RPC without programming, follow these instructions
please support GZIP compression for XML-RPC (in your HTTP request should be Accept-Encoding: gzip), it can save around 97.5% of bandwidth, so it is faster, it is better. Also try to support gzip in your REQUEST XML-RPC (HTTP header content-encoding: gzip) - for example very useful when uploading subtitles (no need to compress them...),
for XML-RPC and HTTP (download subtitles for example) requests use registered USERAGENT in HTTP HEADERs
You can specify preferred language for response also by sending HTTP HEADER "Accept-Language"
when downloading subtitles using standard HTTP we added HTTP RESPONSE HEADER: Download-Quota: %d, where %d is number how many subtitles can user still download.
it is REQUIRED that your implementation supports LogIn() with user credentials (manually input user and password), because there are quite a lot of IPs, which are proxy (some service providers NAT, Singapore, Iran and others), and there is download limit per IP, so those users will hit limit very soon and OS will be not usable for them. Also there is other important reasons why to support this (VIP membership and so on). Also NEVER put in your application registered username and password, it might be blocked.
VIP Users should communicate with VIP API server, please read more in LogIn()
if you are sending subtitle contents for analysis (example DetectLanguage()), please always send WHOLE subtitle file, because results of analysis can be different if you sent just portion.
when downloading subtitles from server, you can set up 3-5 retries, 1-5 seconds delay. Don't abuse server with unlimited download retries and small (or no) delay
for manipulating subtitles (convert formats, change encoding, synchronize (time shift, change FPS), detect language, detect encoding) we recommend you check out Subtitles API

Common errors

After reviewing database with movie-hashes, we found developers often make these errors

moviebytesize set to low integer, so overflow happens. Don't forget files can be more than 8GB big (8.589.934.592 bytes), so make sure you allocate right variable for moviebytesize (string is OK)!
moviehash in 99,999% can not be '0000000000000000' (we are ignoring them now, but it is error)
always pass all Method Parameters as string, because some unwanted conversion can occur. For example moviebytesize pass as string "4249049694" and NOT as int 4249049694.

XMLRPC methods

ServerInfo

array ServerInfo( ) This simple function returns basic server info, it could be used for ping or telling server info to client, no valid UserAgent is needed, so it is also good for testing XML-RPC.

Example output:

Array
(
    [xmlrpc_version] => 0.1
    [xmlrpc_url] => http://api.opensubtitles.org/xml-rpc
    [application] => OpenSuber v0.2
    [contact] => admin@opensubtitles.org
    [website_url] => http://www.opensubtitles.org
    [users_online_total] => 5117
    [users_online_program] => 3685
    [users_loggedin] => 55
    [users_max_alltime] => 27449
    [users_registered] => 1025195
    [subs_downloads] => 765919208
    [subs_subtitle_files] => 1864277
    [movies_total] => 136445
    [movies_aka] => 277672
    [total_subtitles_languages] => 61
    [last_update_strings] => Array
        (
            [ar] => 2007-02-03 21:36:14
            ...
        )
    [download_limits] => Array
        (
            [global_24h_download_limit] => 200
            [client_ip] => 1.1.1.1
            [limit_check_by] => user_ip
            [client_24h_download_count] => 0
            [client_download_quota] => 200
            [client_24h_download_limit] => 200
        )
    [seconds] => 0.006
)

Fields explanation: All field are self-explained

array LogIn( $username, $password, $language, $useragent ) This will login user. This function should be called always when starting talking with server. It returns token, which must be used in later communication. If user has no account, blank username and password should be OK. As language - use ISO639 2 letter code and later communication will be done in this language if applicable. You can also pass language in HTTP ACCEPT-LANGUAGE header. Note: when username and password is blank, status is 200 OK, because we want allow anonymous users too. Useragent cannot be empty string. For $useragent use your registered useragent, also provide version number - we need tracking version numbers of your program. If your UA is not registered, you will get error 414 Unknown User Agent.

Important: for security improvement, you can use HTTPS and/or send $password as MD5($password) hash.

Note: don't send any cookies using XML-RPC communication. If VIP user is logged, in HTTP response headers and XML-RPC [data] field is returned: Content-Location: https://vip-api.opensubtitles.org/xml-rpc - your application should change host to continue communicating with VIP API server. This API server is special for VIP users, it is more stable and faster.

Example output:

    [token] => vjp6t4do4vc30tgfmai3lo3db6
    [status] => 200 OK
    [data] => Array
        (
            [IDUser] => 6
            [UserNickName] => os
            [UserRank] => super admin
            [UploadCnt] => 296
            [UserPreferedLanguages] => cze,eng,slo,tha
            [DownloadCnt] => 1215
            [UserWebLanguage] => en
            [Content-Location] => https://vip-api.opensubtitles.org/xml-rpc
        )
    [seconds] => 0.496

Fields explanation:

token => this token string (session id) must be used in later communication
data => array - data of logged in user
status => status code
seconds => how long time takes this process on server

LogOut

string LogOut( $token ) This will logout user (ends session id). Good call this function is before ending (closing) clients program.

Example output:

    [status] => 200 OK
    [seconds] => 0.055

Fields explanation: All field are self-explained

SearchSubtitles

array SearchSubtitles( $token, array(array('sublanguageid' => $sublanguageid, 'moviehash' => $moviehash, 'moviebytesize' => $moviesize, imdbid => $imdbid, query => 'movie name', "season" => 'season number', "episode" => 'episode number', 'tag' => tag ),array(...)), array('limit' => 500))

Returns information about found subtitles. It is designed making multiple search at once. When nothing is found, 'data' is empty. If sublanguageid is empty, or have value 'all' - it search in every sublanguage, you can set it to multiple languages (e.g. 'eng,dut,cze'). Tag is index of movie filename or subtitle file name, or release name - currently we index more than 53.000.000 of tags.

If you define moviehash and moviebytesize, then imdbid and query in same array are ignored. If you define imdbid, then moviehash, moviebytesize and query is ignored. If you define query, then moviehash, moviebytesize and imdbid is ignored. Pseudocode:

if(defined($moviehash) and defined($moviebytesize)) {
  // search by $moviehash and $moviebytesize
} elseif (defined($tag)) {
  //search by $tag
} elseif (defined($imdbid)) {
  // search by $imdbid
} elseif (defined($query)) {
  // fulltext search by $query
} else {
  // empty result
}

Some data (IDSubMovieFile, MovieHash, MovieByteSize, MovieTimeMS) are set to 0, when searching by imdbid or query
Max results is set to 500 found items in total, optional argument limit (in another array, possible to add some more global variables) - you can control limit of total results < 500
Max search conditions are limited to 500 to avoid huge queries.
Season and Episode are not mandatory, when using query/imdb searching
For perfect matches use moviehash/moviebytesize searching, for movie matches use tag/imdbid searching, if you can not use any of them, use fulltext search (least accurate)
If used this method in movie player and subtitles are found using imdbid or query, should be nice to implement Automatic Uploading, so we get back movie hash of matching movie
MatchedBy can be: moviehash, imdbid, tag, fulltext (so you know from where results comes from)
SubTSGroup - read explanation here https://forum.opensubtitles.org/viewtopic.php?f=8&t=15669
when searching by imdbid it is possible to add tags case-insensitive parameter. It can contain comma delimited values. Valid tags parameter is for example 'AXXO,DVD', that means it will return all subtitles for AXXO release AND DVD format. See supported tags
For user convenience when using fulltext search, implement #QuickSuggest
you might use REST JSON search instead of XML-RPC SearchSubtitles()

Tip: you can combine your searches array as you want, so things like

array(
   array('query' => 'south park', 'season' => 1, 'episode' => 1, 'sublanguageid'=>'all'),
   array('imdbid' => '1129442', 'sublanguageid' => 'eng'),
   array('imdbid' => '1129442', 'season' => 1, 'episode' => 1, 'tags' => 'axxo,dvd')
   array('query' => 'matrix', 'sublanguageid' => 'cze,slo'),
   array('moviehash' => '18379ac9af039390', 'moviebytesize' => 366876694),
   array('tag' => 'heroess01e08.avi'), //you can add also imdbid here
),
array(
   'limit' => 100
)

are possible :)

Example output:

Fields explanation: Only for matched by fulltext and tag: QueryNumber is array number in queries sent, starts from 0. QueryParameters is original search parameters for given query.

for SubDownloadLink you can pass other parameters, such as charset encoding, and subtitle format (BETA)

VALID parameters:

http://dl.opensubtitles.org/en/download/filead/src-api/vrf-ef3a1f1e6e/sid-f5d2c3grp3kle26jkt1m7b6et4/1954677189.gz
http://dl.opensubtitles.org/en/download/filead/src-api/vrf-ef3a1f1e6e/sid-f5d2c3grp3kle26jkt1m7b6et4/1954677189
http://dl.opensubtitles.org/en/download/subencoding-utf8/filead/src-api/vrf-ef3a1f1e6e/sid-f5d2c3grp3kle26jkt1m7b6et4/1954677189
http://dl.opensubtitles.org/en/download/subencoding-utf8/filead/src-api/vrf-ef3a1f1e6e/sid-f5d2c3grp3kle26jkt1m7b6et4/1954677189.gz
http://dl.opensubtitles.org/en/download/subformat-vtt/filead/src-api/vrf-ef3a1f1e6e/sid-f5d2c3grp3kle26jkt1m7b6et4/1954677189

format VTT is always encoded in UTF8

Other: All field are self-explained.

SearchToMail

array SearchToMail( $token, array( $sublanguageid, $sublanguageid, ...), array( array( 'moviehash' => $moviehash, 'moviesize' => $moviesize), array( 'moviehash' => $moviehash, 'moviesize' => $moviesize), ...) )'

This is possible only for logged-in users. Scenario: user have directory with movies, for which he cannot find subtitles. With this function he subscribe to possible results, when someone else will upload matching subtitles. Once a day (or week...based on users profile) will system send subtitle link by mail to user. *Note for developers*: if it is possible, send moviehashes and moviesizes only for first CD in set (for example movie on two CDs), because users will receive duplicated mails (one for first cd and one for second cd)

Example output:

    [status] => 200 OK
    [seconds] => 1.211

Fields explanation: if no sublanguageid is given (first array is empty), it means system will try to find subtitles in all languages.

CheckSubHash

array CheckSubHash( $token, array($subhash, $subhash, ...) )

This method returns !IDSubtitleFile, if Subtitle Hash exists in database. If not exists, it returns '0'.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [a9672c89bc3f5438f820f06bab708067] => 1
            [0ca1f1e42cfb58c1345e149f98ac3aec] => 3
            [11111111111111111111111111111111] => 0
        )
    [seconds] => 0.009

Fields explanation: Array in data contains $subhash => $idsubtitlefile

CheckMovieHash

array CheckMovieHash( $token, array($moviehash, $moviehash, ...) )

This method returns best matching !MovieImdbID, MovieName, MovieYear, if available for each $moviehash. See also CheckMovieHash2(). Read more about Movie Identification. Note: method accepts only first 200 hashes to avoid database load, not processed hashes are included in "not_processed". This method is similar to !CheckMovieHash2 - it uses same SQL query, but prints just best guesses.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [46e33be00464c12e] => Array
                (
                    [MovieHash] => 46e33be00464c12e
                    [MovieImdbID] => 2816136
                    [MovieName] => "Game of Thrones" Two Swords
                    [MovieYear] => 2014
                    [MovieKind] => episode
                    [SeriesSeason] => 4
                    [SeriesEpisode] => 1
                    [SeenCount] => 19823
                    [SubCount] => 217
                )

            [53fc6fe84ad5ee31] => Array
                (
                    [MovieHash] => 53fc6fe84ad5ee31
                    [MovieImdbID] => 1185913
                    [MovieName] => "Heroes" Chapter Three 'One of Us, One of Them'
                    [MovieYear] => 2008
                    [MovieKind] => episode
                    [SeriesSeason] => 3
                    [SeriesEpisode] => 3
                    [SeenCount] => 10886
                    [SubCount] => 111
                )

            [abcdefg123211222] => Array
                (
                )

        )

    [not_processed] => Array
        (
        )

    [seconds] => 0.133

Fields explanation: Array in data contains $moviehash => array(), even for unmatched moviehashes.

CheckMovieHash2

array CheckMovieHash2( $token, array($moviehash, $moviehash, ...) )

This method returns matching !MovieImdbID, MovieName, MovieYear, SeriesSeason, SeriesEpisode, MovieKind if available for each $moviehash, always sorted by MovieHash ASC, SubCount DESC, SeenCount DESC. Read more about Movie Identification.

Example output:

Fields explanation: Array in data contains $moviehash => array(), only for matched moviehashes.

InsertMovieHash

array InsertMovieHash( $token, array( array('moviehash' => $moviehash, 'moviebytesize' => $moviebytesize, 'imdbid' => $imdbid, 'movietimems' => $movietimems, 'moviefps' => $moviefps, 'moviefilename' => $moviefilename), array(...) ) )

Inserts or updates data to tables, which are used for CheckMovieHash() and !CheckMovieHash2(). Requested parameters are: moviehash, moviebytesize, imdbid, all rest parameters are optional, but preferred to supply them. Before accepting moviehashes, each moviehash is checked against log table if user doesn't already send it. Read more about Movie Identification.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [accepted_moviehashes] => Array
                (
                    [0] => 53fc6fe84ad5ee31
                    [1] => 3b2ae156d8c11f7a
                )

            [new_imdbs] => Array
                (
                )

        )

    [seconds] => 0.014

Fields explanation: accepted_moviehashes - hashes, which was inserted or updated, new_imdbs - imdb ids need to download from imdb.com

TryUploadSubtitles

array TryUploadSubtitles( $token, array('cd1' => array('subhash' => $submd5hash, 'subfilename' => $subfilename, 'moviehash' => $moviehash, 'moviebytesize' => $moviesize, 'movietimems' => $movietimems, 'movieframes' => $movieframes, 'moviefps' => $moviefps, 'moviefilename' => $moviefilename), 'cd2' => array(...) ) )

This function needs to be called before UploadSubtitles(), because it is possible subtitles already exists on server - this method is designed to link subtitles and moviehash. It takes 2 parameters, second parameter is array of information for subtitles to be uploaded, minimum cd1 is required. Mandatory fields are: subhash (md5 of subtitles), subfilename, moviehash, moviebytesize, moviefilename. It returns "alreadyindb" when subtitles already exists in database. When they do not exists, SearchSubtitles() is called, and API is looking for existing subtitles based on MovieHash/MovieSize. If some results are found, information is returned in "data" key as SearchSubtitles() return structure. This is good for uploading - user should have imdbid field already filled.

Example output when subtitles already exists in database:

    [status] => 200 OK
    [alreadyindb] => 1
    [data] => Array
        (
            [IDSubtitle] => 1
            [SubLanguageID] => eng
            [IDMovieImdb] => 103644
            [MovieName] => AlienÂł
            [MovieYear] => 1992
            [MoviefilenameWasAlreadyInDb] => 0
            [HashWasAlreadyInDb] => 1
        )
    [seconds] => 0.078

MoviefilenameWasAlreadyInDb - if 0, it means new moviefilename was inserted to database. HashWasAlreadyInDb - if 0, it means new MovieHash was inserted to database.

Example output when subtitles are not in database:

(moviesize and moviehash exists in db, but not subhash, on client side should be filled IDMovieImdb from this info)
    [status] => 200 OK
    [alreadyindb] => 0
    [data] => Array
        (
            [0] => Array
                (
                    [IDSubMovieFile] => 739
                    [MovieHash] => 09a2c497663259cb
                    [MovieByteSize] => 733589504
                    [MovieTimeMS] => 0
                    [MovieFrames] => 0
                    [IDSubtitleFile] => 963
                    [SubFileName] => Night Watch (Nochnoj Dozor) (2004) [1 of 2].srt
                    [SubActualCD] => 1
                    [SubSize] => 30677
                    [SubHash] => 6c2bdbb308760205146cb2807dfc32f6
                    [IDSubtitle] => 771
                    [UserID] => 37047
                    [SubLanguageID] => eng
                    [SubFormat] => srt
                    [SubSumCD] => 2
                    [SubAuthorComment] => 
                    [SubAddDate] => 2005-05-23 07:47:04
                    [SubBad] => 0
                    [SubRating] => 0.0
                    [SubDownloadsCnt] => 315
                    [IDMovie] => 516
                    [IDMovieImdb] => 403358
                    [MovieName] => Nochnoy dozor
                    [MovieNameEng] => Night Watch
                    [MovieYear] => 2004
                    [MovieImdbRating] => 6.3
                    [UserNickName] => onefox
                    [ISO639] => en
                    [LanguageName] => English
                    [SubDownloadLink] => http://www.opensubtitles.org/en/download/file/963.gz
                )
        )
    [seconds] => 0.132

Fields explanation: All field are self-explained.

UploadSubtitles

array UploadSubtitles( $token,array( 'baseinfo' => array ( 'idmovieimdb' => $idmovieimdb, 'moviereleasename' => $scene_releasename, 'movieaka' => $aka_in_subtitle_language, 'sublanguageid' => $sublanguageid, 'subauthorcomment' => $author_comment, 'hearingimpaired' => $hearing_impaired, 'highdefinition' => $high_definition, 'automatictranslation' => $automatic_translation, 'subtranslator' => $who_translated_subtitles, 'foreignpartsonly' => $foreign_parts_only), 'cd1' => array( 'subhash' => $md5subhash, 'subfilename' => $subfilename, 'moviehash' => $moviehash, 'moviebytesize' => $moviebytesize, 'movietimems' => $movietimems, 'moviefps' => $moviefps, 'movieframes' => $movieframes, 'moviefilename' => $moviefilename, 'subcontent' => $subtitlecontent ), 'cd2' => array (...) ) )

This function have to be called after TryUploadSubtitles(). Many information are same, important part is subcontent. It should be gzip-ed (without header) and must be base64 encoded. Also please don't put any advertisment (eg. Uploaded by My Application) anywhere (eg. subauthorcomment), it will be deleted. sublanguageid - is optional, if it is not present, or is set to not allowed language string (eg 'unk'), auto-detection language of subtitles will be performed. Optional parameters in this method are: moviereleasename, movieaka, sublanguageid, subauthorcomment, hearingimpaired, highdefinition, automatictranslation, movietimems, moviefps, movieframes. If hearingimpaired, highdefinition and automatictranslation are not defined, set to 0 or empty flag will be not set.

Example output:

    [status] => 200 OK
    [data] => http://www.opensubtitles.org/subtitles/123456
    [seconds] => 1.171

Fields explanation: data is absolute link to subtitles.

DetectLanguage

array DetectLanguage( $token, array($text, $text, ...) )

Returns array of MD5 => ISO639-2 language codes, trying to detect language for given $text. Note: $text MUST be base64 encoded and should be gzipped (without header), for save some bandwidth and for better speed. MD5 is md5() of unpacked text, please send whole file of text subtitles, not a portion.

Example output:

    [status] => 200 OK
    [data] => Array
       (
            [9e107d9d372bb6826bd81d3542a419d6] => eng
            [ffd93f16876049265fbaef4da268dd0e] => cze
            ...
       )
    [seconds] => 0.625

Fields explanation: All fields are self-explained. Note: if you get instead of 3 characters language some other language name - please contact us with input/output text (for example you can get scots), we will analyze that file.

PreviewSubtitles

array PreviewSubtitles( $token, array($IDSubtitleFile, $IDSubtitleFile,...) )

Returns BASE64 encoded gzipped preview for IDSubtitleFile(s). You need to BASE64 decode and ungzip 'data' to get its contents. LIMIT is for maximum 20 IDSubtitleFiles, others will be ignored.

Example output:

Array
(
    [status] => 200 OK
    [data] => Array
        (
            [0] => Array
                (
                    [encoding] => UTF-8
                    [contents] => MQ0KMDA6MDA6MDIsNjkzIC0tPiAwMDowM....
                )

            [1] => Array
                (
                    [encoding] => CP932
                    [contents] => MQ0KMDA6MDA6MDYsMDAwIC0tPiAwMDow...
                )

        )

    [seconds] => 0.01
)

DownloadSubtitles

array DownloadSubtitles( $token, array($IDSubtitleFile, $IDSubtitleFile,...) )

Returns BASE64 encoded gzipped IDSubtitleFile(s). You need to BASE64 decode and ungzip 'data' to get its contents. LIMIT is for maximum 20 IDSubtitleFiles, others will be ignored.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [0] => Array
                (
                    [idsubtitlefile] => 10
                    [data] => MQ0KMDA6MDA6MzgsMzAwIC0tPiAwMDowMDo0MSwwMDA...
                )
            [1] => Array
                (
                    [idsubtitlefile] => 20
                    [data] => MQ0KMDA6MDA6MjYsMjgzIC0tPiAwMD...
                )
    [seconds] => 0.397

Fields explanation: All field are self-explained.

ReportWrongMovieHash

array ReportWrongMovieHash( $token, $IDSubMovieFile )

This method is needed to report bad hash, e.g. subtitles are right for this movie file, but they are de-synchornized - for other version/release. With this method number of reports is counted in db, and after some number, hash will be automatically deleted from database.

Example output:

    [status] => 200 OK
    [seconds] => 0.115

Fields explanation: All field are self-explained.

ReportWrongImdbMovie

array ReportWrongImdbMovie( $token, array('moviehash' => $moviehash, 'moviebytesize' => $moviebytesize, 'imdbid' => $imdbid )

This method is needed to report bad movie hash for imdbid. This method should be used for correcting wrong entries, when using CheckMovieHash?/CheckMovieHash2. Pass moviehash and moviebytesize for file, and imdbid as new, corrected one IMDBID (id number without trailing zeroes). After some reports, moviehash will be linked to new imdbid.

Example output:

    [status] => 200 OK
    [seconds] => 0.115

Fields explanation: All field are self-explained.

GetSubLanguages

array GetSubLanguages( $language = 'en' )

Returns list of allowed subtitle languages, default is english language. Use ISO639-1 (2 characters code)

Example output:

    [data] => Array
        (
            [0] => Array
                (
                    [SubLanguageID] => alb
                    [LanguageName] => Albanian
                    [ISO639] => sq
                )
            [1] => Array
                (
                    [SubLanguageID] => ara
                    [LanguageName] => Arabic
                    [ISO639] => ar
                )
            ...
    [seconds] => 0.043

Fields explanation: data - array of enabled subtitle languages. !SubLanguageID - iso639-2 3 characters code of language. LanguageName - translated language name. ISO639 - ISO639-1 2 characters code.

GetAvailableTranslations

array GetAvailableTranslations( $token, $program )

Returns array of available translations for a program. In array you can find date of last created string and number of strings. Current supported programs are 'subdownloader' and 'oscar'

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [en] => Array
                (
                    [LastCreated] => 2007-02-03 21:36:14
                    [StringsNo] => 438
                )
            [ar] => Array
                (
                    [LastCreated] => 2007-02-26 11:32:20
                    [StringsNo] => 438
                )
            ...
    [seconds] => 0.486

Fields explanation: All field are self-explained.

GetTranslation

array GetTranslation( $token, $iso639, $format, $program )

Returns base64 encoded strings for language ($iso639) in some $format (mo, po, txt, xml). Use ISO639-1 (2 characters code), $program should be 'subdownloader' or 'oscar'

Example output:

    [status] => 200 OK
    [data] => bXNnaWQgIiINCm1zZ3N0ciAiIg0KIlByb2plY3QtSWQtVmVyc2lvbjogT3BlblN1YnRp...
    [seconds] => 0.192

Fields explanation: data - base64 encoded contents

SearchMoviesOnIMDB

array SearchMoviesOnIMDB( $token, $query )

Returns array of movies, which was found on imdb.com and in opensubtitles internal movie database where id starts at 10000000. Query is first fixed for some strings (deleted dvdrip and so on). IMPORTANT: on our server is executed external program for every query (parser), so don't use this function too often, better use 3rd parties libraries (example: https://www.npmjs.org/package/imdb-api http://imdbpy.sourceforge.net/ http://search.cpan.org/~stepanov/IMDB-Film-0.53/lib/IMDB/Film.pm http://projects.izzysoft.de/trac/imdbphp etc.) If you will overload this function with requests, your UA might be disabled.

Example output for 'troy':

    [status] => 200 OK
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 0332452
                    [title] => Troy (2004)
                )

            [1] => Array
                (
                    [id] => 0340477
                    [title] => Helen of Troy (2003) (TV)
                )
            ...
    [seconds] => 0.441

Fields explanation: title - title of movie, id - imdbid/opensubtites movie id

GetIMDBMovieDetails

array GetIMDBMovieDetails( $token, $imdbid )

This method should be used only, when you can not use some existing libraries. IMPORTANT: on our server is executed external program for every query (parser), so don't use this function too often, better use 3rd parties libraries (example: https://www.npmjs.org/package/imdb-api http://imdbpy.sourceforge.net/ http://search.cpan.org/~stepanov/IMDB-Film-0.53/lib/IMDB/Film.pm http://projects.izzysoft.de/trac/imdbphp etc.) If you will overload this function with requests, your UA might be disabled.

Returns array, info for $imdbid from www.imdb.com.

Example output for '0480011':

    [status] => 200 OK
    [data] => Array
       (
            [cast] => Array
                (
                    [_0000096] => Gillian Anderson
                    [_0245705] => Danny Dyer
                    ...
                )
            [rating] => 5.9
            [cover] => http://ia.imdb.com/media/imdb/01/I/48/24/52/10m.jpg
            [id] => 0480011
            [votes] => 919
            [title] => Straightheads
            [aka] => Array
                (
                    [0] => Closure (USA) (DVD title)
                )

            [year] => 2007            
            ...
       )
    [seconds] => 0.441

Fields explanation: All fields are self-explained.

InsertMovie

array InsertMovie( $token, array('moviename' => $moviename, 'movieyear' => $movieyear) )

Allows logged users insert new movies to opensubtitles internal movie database, which are not in IMDB.com. Guidelines for application: when user enters movie name and movie year call in your app SearchMoviesOnIMDB() where are returned movies stored in imdb.com and opensubtitles.org. When user checks movie does not exists in list, allow him to insert new movie. This needs to be done to avoid duplicates.

Example output:

    [status] => 200 OK
    [id] => 10000044
    [seconds] => 0.441

Fields explanation: id is idmovie in opensubtitles.org movie database for inserted movie. You can use it later for uploading subtitles.

SubtitlesVote

array SubtitlesVote( $token, array('idsubtitle' => $idsubtitle, 'score' => $score) )

Allows logged users vote for subtitles. Score must be from interval 1 to 10. If user will vote more than 1 time for same subtitles, next votes will be not counted.

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [SubRating] => 8.0
            [SubSumVotes] => 1
            [IDSubtitle] => 3331501
        )

    [seconds] => 0.075

Fields explanation: SubRating is average subrating for given subtitles. SubSumVotes is how much times was voted for subtitles.

GetComments

array GetComments( $token, array($idsubtitle, $idsubtitle, ...))

Returns comments for subtitles

Example output:

    [status] => 200 OK
    [data] => Array
        (
            [_3387112] => Array
                (
                    [0] => Array
                        (
                            [IDSubtitle] => 3387112
                            [UserID] => 192696
                            [UserNickName] => neo_rtr
                            [Comment] => Greate Work. thank you
                            [Created] => 2008-12-14 17:20:42
                        )

                )
            [_3385570] => Array
                (
                    [0] => Array
                        (
                            [IDSubtitle] => 3385570
                            [UserID] => 745565
                            [UserNickName] => pee-jay_cz
                            [Comment] => Thank you.
                            [Created] => 2008-12-12 15:21:48
                        )
                    [1] => Array
                        (
                            [IDSubtitle] => 3385570
                            [UserID] => 754781
                            [UserNickName] => Guzeppi
                            [Comment] => You're welcome :)
                            [Created] => 2008-12-12 15:51:01
                        )
                )
        )
    [seconds] => 0.02

Fields explanation: All field are self-explained.

AddComment

array AddComment( $token, array('idsubtitle' => $idsubtitle, 'comment' => $comment, 'badsubtitle' => $int) )

Allows logged users add new comment to subtitles. badsubtitle is optional, if set to 1, subtitles are marked as bad

Example output:

Array
(
    [status] => 200 OK
    [seconds] => 0.228
)

Fields explanation: All field are self-explained.

AddRequest

array AddRequest( $token, array('sublanguageid' => $sublanguageid, 'idmovieimdb' => $idmovieimdb, 'comment' => $comment ) )

Add new request for subtitles, user must be logged in. All parameters are mandatory except comment field - you can put there releasename of movie. You should call this method, when no subtitles are found for given IMDB (not for moviehash!) and it should be done on user request. When request is filled, user should receive mail from opensubtitles.org about that.

Example output:

Array
(
    [status] => 200 OK
    [data] => Array
        (
            [request_url] => http://www.opensubtitles.net/en/requestd/idmovie-887/sublanguageid-cze
        )

    [seconds] => 7.676
)

Fields explanation: All field are self-explained.

SetSubscribeUrl

array SetSubscribeUrl( $token, $url )

Set webhook $url. Use HTTP (HTTPS was not tested). Example $url can be 'http://www.opensubtitles.org/addons/webhook-test.php'. To this url will be POSTed results of SubscribeToHash() Example output:

Array
(
    [status] => 200 OK
    [data] => URL for webhook was set: http://www.opensubtitles.org/addons/webhook-test.php
    [seconds] => 0.031
)

Fields explanation: All field are self-explained.

SubscribeToHash

array SubscribeToHash( $token, array ($moviehash, $moviehash, ... ) )

Subscribes to $moviehash. Once subtitle is linked to $moviehash, SearchSubtitles() results are POSTed to $url (set in SetSubscribeUrl()). This method is implementation of webhook, it is useful, when you got some moviehashes and you don't want to scan OpenSubtitles? for subtitles for performance reason.

Example output:

Array
(
    [status] => 200 OK
    [data] => Subscribed to 3 moviehashes
    [seconds] => 0.033
)

Fields explanation: All field are self-explained.

QuickSuggest

array QuickSuggest( $token, $string, $sublanguageid )

This method is useful for when a user is typing a movie or series name in a search field. Use-case scenario; The user is in the Search Subtitles -pane of a program and searching for subtitles. He starts typing and this method returns the count of existing subtitles for the given languages. Then he selects a movie or series and a SearchSubtitles by IDMovieIMDB is performed. $sublanguageid can be multiple languages (eg.: "eng,por,pob"). The results are ordered by popularity of movie. The SubtitlesFound is always higher than 0. This method is not suitable to implement in an Upload function of a program (because only existing IMDb IDs are returned that have suitable subtitles). $sublanguageid is optional. If not specified, $sublanguage == 'all'. In that case, suggestions are made for All languages. So it is a good idea to pass user-defined subtitle language(s) here.

We're using the same logic and data on our website. The URL for JSON output is http://www.opensubtitles.org/libs/suggest.php?format=json3&MovieName=m&SubLanguageID=eng,por,pob. But if possible, please use the xml-rpc method.

Example output for $string = 'm', $sublanguageid = 'eng,por,pob':

Array
(
    [status] => 200 OK
    [data] => Array
        (
            [0] => Array
                (
                    [SubtitlesFound] => 70
                    [MovieName] => Martian
                    [MovieYear] => 2015
                    [IDMovieIMDB] => 3659388
                    [MovieKind] => movie
                    [MovieImdbRating] => 8.1
                )

            [1] => Array
                (
                    [SubtitlesFound] => 2133
                    [MovieName] => Modern Family
                    [MovieYear] => 2009
                    [IDMovieIMDB] => 1442437
                    [MovieKind] => tv
                    [MovieImdbRating] => 8.6
                )

            [2] => Array
                (
                    [SubtitlesFound] => 51
                    [MovieName] => Minions
                    [MovieYear] => 2015
                    [IDMovieIMDB] => 2293640
                    [MovieKind] => movie
                    [MovieImdbRating] => 6.5
                )

            [3] => Array
                (
                    [SubtitlesFound] => 60
                    [MovieName] => Mission: Impossible - Rogue
                    [MovieYear] => 2015
                    [IDMovieIMDB] => 2381249
                    [MovieKind] => movie
                    [MovieImdbRating] => 7.5
                )

            [4] => Array
                (
                    [SubtitlesFound] => 8
                    [MovieName] => Mr. Right
                    [MovieYear] => 2015
                    [IDMovieIMDB] => 2091935
                    [MovieKind] => movie
                    [MovieImdbRating] => 6.3
                )

        )

    [seconds] => 0.002
)

Fields explanation: All field are self-explained.

SuggestMovie

array SuggestMovie( $token, $string )

WARNING!!! BETA QUALITY - THIS METHOD CAN CHANGE IN FUTURE, CONTACT US FOR MORE INFO

This can be used for suggesting movies with imdb code, while user type, $string can be minimum 1 character long. It returns movie infos ordered by priority (best guess/popularity). Use-case scenario for filling imdb id for example UploadSubtitles()

Example output for $string = 'matrix':

Array
(
    [status] => 200 OK
    [data] => Array
        (
            [matrix] => Array
                (
                    [0] => Array
                        (
                            [MovieName] => The Matrix
                            [MovieYear] => 1999
                            [MovieKind] => movie
                            [IDMovieIMDB] => 0133093
                        )

                    [1] => Array
                        (
                            [MovieName] => The Matrix Reloaded
                            [MovieYear] => 2003
                            [MovieKind] => movie
                            [IDMovieIMDB] => 0234215
                        )

                    [2] => Array
                        (
                            [MovieName] => The Matrix Revolutions
                            [MovieYear] => 2003
                            [MovieKind] => movie
                            [IDMovieIMDB] => 0242653
                        )

                    [3] => Array
                        (
                            [MovieName] => CR: Enter the Matrix
                            [MovieYear] => 2009
                            [MovieKind] => movie
                            [IDMovieIMDB] => 1675286
                        )

                )

        )

    [seconds] => 0.004
)

Fields explanation: All field are self-explained.

GetUserInfo

array GetUserInfo( $token )

Returns info about logged-in user. Example:

(
    [status] => 200 OK
    [data] => Array
        (
            [IDUser] => 6
            [UserNickName] => os
            [UserRank] => super admin
            [UploadCnt] => 296
            [UserPreferedLanguages] => cze,eng,slo,tha
            [DownloadCnt] => 1215
            [UserWebLanguage] => en
        )
    [seconds] => 0.241
)

Fields explanation: All field are self-explained.

GuessMovieFromString

array GuessMovieFromString( $token, array($string, ... ) )

WARNING!!! BETA QUALITY - THIS METHOD CAN CHANGE IN FUTURE, CONTACT US FOR MORE INFO

Provides best guess for IMDB ID from any string. String can be file name of movie, or directory name. This method might be very slow, because it makes comparison in real time from different sources (then it is cached). You can use maximum 3 strings, others are ignored for performance reasons.

Example output for $string = 'Aliens 1080p BluRay AC3 x264-ETRG.mkv', you might want data from BestGuess

Fields explanation: All field are self-explained.

AutoUpdate

array AutoUpdate ( $program_name )

This function returns latest version with info for $program_name

Example output:

    [version] => 1.2.3
    [url_windows] => http://forja.rediris.es/frs/download.php/123/subdownloader1.2.3.exe
    [url_linux] => http://forja.rediris.es/frs/download.php/124/SubDownloader1.2.3.src.zip
    [comments] => MultiUpload CDs supported(more than 2CDs)|Lots of bugs fixed
    [status] => 200 OK

If $program_name is invalid it returns:
    [status] => 408 Invalid parameters

Fields explanation: All field are self-explained.

NoOperation

array NoOperation( $token )

This function should be called each 15 minutes after last request to xmlrpc. It is used for not expiring current session. It also returns if current $token is registered.

Example output when token is registered:

    [status] => 200 OK
    [seconds] => 0.055

When it is not registered, in client should be called LogIn() again. Example of response:

    [status] => 406 No session
    [seconds] => 0.061

Fields explanation: All field are self-explained.

Status codes

XMLRPC should always return status code. For 2xx it means operation was sucessful, for 4xx it means there was some error and client should display this error to user.

Successful 2xx

200 OK
206 Partial content; message

Moved 3xx

301 Moved (host)

Errors 4xx

401 Unauthorized
402 Subtitles has invalid format
403 SubHashes (content and sent subhash) are not same!
404 Subtitles has invalid language!
405 Not all mandatory parameters was specified
406 No session
407 Download limit reached
408 Invalid parameters
409 Method not found
410 Other or unknown error
411 Empty or invalid useragent
412 %s has invalid format (reason)
413 Invalid ImdbID
414 Unknown User Agent
415 Disabled user agent
416 Internal subtitle validation failed
417 Upload disabled

Server Error 5xx

503 Service Unavailable
506 Server under maintenance

HTTP RESPONSE CODES

200 OK (this should be default response)

429 Too many requests (too many requests sent, read more https://forum.opensubtitles.org/viewtopic.php?f=8&t=16072)

503 Service Unavailable (when server is under heavy load, it is temporary, retry in 1 second)

UserRank lists

administrator
app developer
bronze member
gold member
moderator
platinum member
read only
silver member
subtranslator
super admin
translator
trusted
vip member
vip plus member
warning

(can be also empty string)

Supported tags

Tags are extracted from subtitle filenames and movie filenames.

release group tags - can be any release group, such as AXXO, KILLERS, FUM etc.

movie format tags:

BluRay
Cam
DVB
DVD
HD-DVD
HDTV
PPV
Telecine
Telesync
TV
VHS
VOD
WEB-DL
WEBRip
Workprint

other movie tags:

3D
Bonus
CC
Classic
Complete
DDC
Extended
Extended Cut
FINAL
Fansub
Fastsub
Fix
Fixed
HD
HDLight
HQ
HR
LD
LiNE
Limited
MD
NF
NTSC
Netflix
None
OV
PAL
Proper
R5
RC
Real
Remastered
Remux
Repack
Rerip
Retail
SECAM
Screener
Trailer
Uncut
Unrated
VO
XXX
mHD

Last modified 3 years ago Last modified on Jan 18, 2022, 6:43:52 AM

Download in other formats:

Plain Text

Context Navigation

Subtitles API

Introduction to OSDb

XMLRPC API Methods

Table of Contents

Instructions

Common errors

XMLRPC methods

ServerInfo

LogIn

LogOut

SearchSubtitles

SearchToMail

CheckSubHash

CheckMovieHash

CheckMovieHash2

InsertMovieHash

TryUploadSubtitles

UploadSubtitles

DetectLanguage

PreviewSubtitles

DownloadSubtitles

ReportWrongMovieHash

ReportWrongImdbMovie

GetSubLanguages

GetAvailableTranslations

GetTranslation

SearchMoviesOnIMDB

GetIMDBMovieDetails

InsertMovie

SubtitlesVote

GetComments

AddComment

AddRequest

SetSubscribeUrl

SubscribeToHash

QuickSuggest

SuggestMovie

GetUserInfo

GuessMovieFromString

AutoUpdate

NoOperation

Status codes

UserRank lists

Supported tags

Download in other formats: